Node / meshtastic / Meshtastic-Android / files / docs / assets / screenshots / README.md

Displaying Rendered • View raw • Download

This directory is the single source of truth for screenshot assets referenced by the

documentation pages. It is consumed by both:

• the Jekyll docs site (markdown references T383838../../assets/screenshots/{name}.png), and

• the in-app docs browser — T383838:feature:docs:syncDocsToComposeResources bundles this

directory into compose resources at T383838files/docs/assets/screenshots/.

T383838DocImageWiringTest (in T383838:feature:docs) fails the build if a doc page references an image

that is not present here.

Doc screenshots come from Compose Preview Screenshot Testing references in two modules:

• T383838:screenshot-tests — visual-regression gate (CI runs T383838:screenshot-tests:validateDebugScreenshotTest).

Holds atomic, dual-purpose components (signal/battery/hops info, list items, preference widgets,

alerts) that are both regression-checked and used as doc images. Don't reframe these for docs.

• T383838:docs-screenshots — generate-only, not gated in CI. Holds doc-framed compositions whose

framing is tuned for the docs site (e.g. the firmware status crops, the connections BLE-scan /

empty-state crops). Reframing one here never churns the regression gate.

T383838copyDocsScreenshots (in T383838:screenshot-tests) aggregates the reference images from both modules.

After changing a UI component, regenerate references for whichever module owns the wrapper, then copy:

T282828

./gradlew :docs-screenshots:updateDebugScreenshotTest T8b949e# doc-framed composition references

./gradlew :screenshot-tests:copyDocsScreenshots T8b949e# refresh this directory from both

T383838copyDocsScreenshots copies only the light-mode reference images that have a semantic

alias in T383838screenshot-tests/docs-screenshot-aliases.properties, renaming them on the way.

Commit the refreshed PNGs together with the reference-image changes.

1. Add (or reuse) a T383838Preview*/T383838*Preview composable with representative mock data in the

feature module. Add a T383838Screenshot* wrapper: in T383838:docs-screenshots if it's a doc-framed

composition (full screen / doc-specific crop), or in T383838:screenshot-tests if it's an atomic

component you also want regression-gated. If the component renders timestamps, give it a

T383838timeTextOverride-style parameter so renders stay deterministic across machines.

2. Make sure the test class is covered by a pattern in T383838screenshot-tests/docs-screenshots-manifest.txt

(the patterns are T383838**/{Class}Kt/..., so they match in either module).

3. Map the semantic name in T383838screenshot-tests/docs-screenshot-aliases.properties:

T383838{page-id}_{description}.png=Screenshot{Name}_Light_{hash}_0.png

4. Run the relevant update task(s) + T383838copyDocsScreenshots, then reference the image from the doc page.

T282828

Examples: T383838onboarding_welcome.png, T383838connections_bluetooth_scan.png, T383838discovery_preset_result.png.

• PNG format, light-mode only (dark variants live in the reference directory)

• Name screenshots to match the docs page they appear in

• Keep filenames lowercase with underscores

• Prefer CST-generated screenshots — they render real app composables, so they cannot drift from

reality. Avoid hand-pasted captures: a stray screenshot from another app slipped in this way

before (the old T383838connections_wifi_*.png were from an unrelated WiFi-provisioning app, not

Meshtastic). If a manual capture is unavoidable, it must be a genuine Meshtastic-Android screen.